EEE 


D 8 
Sy 
Ll 
Ll 
Ll 
Ll 
Ll 
Ll 
Ll 
Ll 
Ll 
Ll 
LLL IIIIIIIII BBBBBBBBBBBB RRRRRRRRRRRR TTTTTTTTTTTTTTT «LLL Ll 
LLL HII BBBBBBBBBBBB RRRRRRRRRRRR TTTTTTTTTTTTITTT «LLL + 
LLL LITT BBB RRRRRRRRRRRR TTTTTTTTTITITITT «LLL L 
LLL 111 BBB BBB RRR RRR TTT LLL | Ll 
LLL II] BB BBB RRR RRR TTT LLL LI 
LLL 11] BBB BBB RRR RRR TTT LLL | Ll 
LLL II] BBB BBB RRR RRR TTT LLL | Ll 
LLL Il] BBB RRR RRR TTT LLL Ll 
LLL Il] BBB BBB RRR RRR TTT LLL Ll 
LLL III B RRRRRRRRRRRR TTT LLL Ll 
LLL Ill BBBBBBBBBBBB RRRRRRRRRRRR TTT LLL LI 
LLL Ill 8 RRRRRRRRRRRR TTT LLL ul 
LLL III BRA BBB RRR RRR TTT LLL 
LLL II] BBB RRR RRR TTT LLL Ll 
LLL II] BER BBB RRR RRR TTT LLL Ll 
LLL II] BRB BBB RRR RRR TTT LLL Ll 
LLL III ERB BBB RRR RRR TTT LLL Ll 
LLL Ill BSB BB RRR RRR TTT LLL Ll 
LLELLLLLLLLLLLLL IIIIIIIII BBBBBBBBBBBB RRR RRR TTT LELLLLLLLLLLLLL Ll 
LLELLLLLLLLLLLLL TITIII111 BBBBBBBBBBBB RRR RRR TTT LI 
LLELLLLLLLLLLLLL LIIIIIII BBBBBBBBBBBB RRR RRR TTT LELLLLLLLLLLLLL 


| 
LLLLLLLLLLLLLLL | 
| 
| 
| 


**F ]LE®*]D**STRMACROS 


| 
| 
SSSSSSSS TITTTTTTTT RRRRRRRR MM MM  —s AAAAAA CCCCCCCC ~RRRRRRRR 000000 SSSSSSSS 
SSSSSSSS_ TITTTTTTTT RRRRRRRR MM MM —s AAAAAA CCCCCCCC ~RRRRRRRR 000000 SSSSSSSS 
ss TT RR R MMMM MMMM AA AA CC RR RR 00 00 ss 
SS TT RR RR MMMM MMMM AA AA CC RR RR 00 00 SS 
SS TT RR MM MM AA AA CC RR RR 00 00 SS 
$s TT RR RR MM AA AA CC RR RR 00 00 Ss 
SSSSSS TT RRRRRRRR Ss MM MM AA AA CC RRRRRRRR 00 00 = SSSSSS 
SSSSSS TT RRRRRRRR ss MM MM AA AA CC RRRRRRRR ~—O0 00 SSSSSS 
Ss TT RR RR i MM AAAAAAAAAA (CC RR RR 00 00 $$ 
Ss TT RR RR MM MM AAAAAAAAAA (CC RR RR 00 00 Ss 
Ss TT RR RR =soMM MM AA AA CC RR ~—s RR 00 00 $s ae 
SS TT RR RR =sMM MM AA AA CC RR ~—s RR 00 00 S$ Sia 
SSSSSSSS TT RR RR MM MM AA AA cCCCCCCC «RR RR 000000 SSSSSSSS i 
SSSSSSSS TT RR RR MM MM AA AA CCCCCCCC ORR RR 000000 SSSSSSSS en 
RRRRRRRR EEEEEEEEEE aaceaa 
RRRRRRRR EEEEEEEEEE aaaaaa 
RR RR EE aa aa 
RR RR EE aa QQ 
RR RR EE QQ a0 
RR RR EE QQ aa 
RRRRRRRR EEEEEEEE aa QQ 
RRRRRRRR EEEEEEEE QQ Q 
RR RR EE QQ aa aa | 
RR RR EE QQ a0 aa 
RR RR €EE aa)0—Ss«k 
RR RR_ €EE ao —s QQ 
RR RR EEEEEEEEEE a00ag aa | 
RR RR EEEEEEEEEE 00a aa 


——— 
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+ <BLF /MACROS> 
x File: STRMACROS.REQ Edit: LEB1034 


i This file, STRMACROS.REQ, defines macros for the string facility 
A to use when manipulating strings. 


i 
i eeeerererereeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeedeeeeeerereneeeeerene 


‘® COPYRIGHT (c) 1978, 1980, 1982, 1984 B 
ie DIGITAL EQUIPMENT CORPORATION, MAYNARD. MASSACHUSETTS. 
't ALL RIGHTS RESERVED. 


® 
te 
® 
® 
i THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 
ie ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE * 
ie INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER * 
ie COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY * 
i OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY * 
ie TRANSFERRED. . 
* 
i THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE * 
i® AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT * 
i CORPORATION. . 
* 
® 
ww 
* 
® 
® 


'® DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR _ RELIABILITY OF ITS 
'® SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 


SRR eRe AAA AERA AAA AEA AAAEAARAAAAAAEAEEA EEE eee eee eee 
' 


lee 

: AUTHOR: R. Will, CREATION DATE: 22-JAN-79 

MODIFIED BY: 

! 1-001 = Original. RW 22-JAN-79 

! 1-002 - Made SSTRSALLOCATE son ipuiste the short string queues 

: directly using REMQUE. JBS 15-MAR-1979 

! 1-003 - Added the ‘discourse on strings . and modified 

: SSTRSDYN_AL_LEN to eerrespns to it. SBS 16-MAR- Hip 

! 1-004 = Put parens around the bod ret. of er AL_LEN n 

! be used as a formal of $STRSNEED_ALLOC. “JBS i2-MA ARS1979 

1 1-005 = Fix the REMQUE instruction in SSTASA SALLOCATE. JBS 15-MAR-1979 
! 1-006 - Redo the STRSS$SHORT_STR structure to improve efficiency and 

: handle the case of a string me? BB Long... JBS 16-MAR-1979 
! 1-007 - Fix some bugs in long strings. 

! 1-008 - Put the body of SSTRSNEED_ALLOC ny parens so " can be used 

! as an expression. 19-MAR-1979 

: 1-009 - — u 02h cree R19 pick up current Length and pointer for strings. 
! 1-010 - chen CHAR to STRSK_FILL_CHAR. JBS 09-APR-1979 

! 1-011 - Make 9F  TREACLOCATE handle-Q-length strings. JBS 15-APR-1979 
: 1~0ig = Signal using the meuiy get ined 3" wesee JBS 16-MAY-1979 
! 1-015 = A null string has length 0. i 

! 1-014 = Change string Linkages to we. with TRS. JBS 04-JUN-1979 
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16-SEP-1984 16:51:45,349 Page 


Fix the allocation of space for STRSSSHORT_STR.JBS 11-JUN-1979 
Change all of the Literals to start with STR$. JBS 21=-JUN-1979 
Change the allocation ma £8 to loop on the REMQUE until it 
succeeds. JBS 21-JUN-197 

Change BASSSSCALE to call a routine. RW -JUN-79 

Change galt to STRSMOVQ_R1. JBS 25-JUL-19 

Undo edit 13. A string with Length 0 may still have space 
allocated to it. RW 17-SEP-197 


' 

i 

i 

i 

i 

i 

! 

! 1-021 = Remove the a tI statement, for the new BLISS compiler. 

: JBS 02-0CT-1979 

! 1-022 = Add macros for class and dtype. Make macros for length and 

' addr suitable for fetch or store. 29-Oct-79 

! 1-023 = Remove SBASSSCALE macro. 29-0ct- 

! 1-024 = Change Linkage name for STRSMOVQ_R1 to track STRLNK.REQ. 

: JBS 31-0CT-1979 

! 1-025 = Add string interlocking. JBS 01-NOV-1979 

! 1-026 = String cleanup, use descriptor accessing macros. RW 8-Nov-79 
! 1-027 = String speedup, no signalling inside macros sontens debugging 
: portion of interlock macros). RW  8=-Jan-1980 

! 1-028 - Remove string interlocks. RW 19-Feb-1980 

! 1-029 = Add macro SSTRSCHECK_STATUS to map LIBS statuses to STR$ 

' signals. and signal fhe fatal errors. 

: Add macros $STRSGET_LEN_ADDR to extract the Length and address 
; of the first data byte of a string from any supported class of 
: string Seeeripter. 

‘ RKR 3-MAY-198 

: 1-030 - Improve SSTRSGET_LEN_ADDR so_as to not declare a named variable 
: to hold the return status. This Fygically frees a register from 
: the Fei ting routine. SBL 28-Sep-1981 

! 1-031 = Rewrite SSTRSGET_LEN_ADDR to use STRSANALYZE_SDESC_R2 rather 

: than LIBSANALYZE-SDESC_R3. STRSANALZYE_SDESC and 

! STRSANALYZE_SDESC_R2 do not returf status, so macro no longer 
' returns status. RKR 19-OCT-1981. 

! 1-032 = Rewrite SSTRSGET_LEN_ADDR to use STRSANALYZE_SDESC_R1. 

' RKR 18-NOV-1981. 

! 1-033 - Declare LIBSSTOP external where necessary. SBL 30-Nov-1981 

: 1-034 - Take away NOVALUE attribute for LIBSSTOP in the SSTRSSIGNAL_FATAL 
! macro so that_it matches the declarations in the .B32 files. 
LEB 9-May-1983 

'<BLF /PAGE> 
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' a class field, and a pointer. These a 

! DSCSB_DTYPE, DSCSB_CLASS and DSCSA_POINTER fields, respectively. 
! The user of the string package uses these fields to indicate the 
' number of bytes in the string, the data type of the stri 

' allocation class, and the address of its 


Discourse on strings: 


A string descriptor consists of a length field, a data ype field, 
i re named the DSC$W_LENGTH, 


ring, its 
2 irst byte. The STR 
tod a provides subroutines to help the user manipulate these 
strings. 


Two classes of strings are supported: Fixed-length and Syneete. 
Fixed-length strings have class field equal to DSCSK_CLASS_S. 
Allocation of the data area pointed to by DSCSA_POINTER is not 
under the control of the descriptor. Typically, the data area | 
is allocated on the stack and will be deallocated when the routine 
whict, allocated it returns to its caller. 


Dynamic err tags have class field equal to DSCSK_CLASS_D. In these 
strings the STR facility allocates and deallocates the data area 
pointed to by DSCSA_POINTER. Thus these strings can be allocated by 
a routine and returned to the routine's caller. 


From the user's point of view there is only one kind of Gyneate 
string, as described above, but the STR facility distinguishes two 
kinds, for efficiency. | shring whose sengeh is less than 240 bytes 
is considered a ‘'short str ng’: he STR facility allocates short 
strings in nuts pres of 8 bytes, and a request for a string of less 
or equal to 240 bytes is satisfied by a previously allocated string 
long enough to handle it. If the List of such strings is empty, more 
are obtained from virtual storage. A short oer ene can be decreased 
in Length (by the STR facility) PY simply shortening the DSC$W_LENGTH 
field, since the string will still be classified as a short string. 
When a short string is allocated, 4 extra bytes are allocated, two 

of which hold a count of the number of bytes which the user can 
access (always a multiple of 8, and always at least as large as he 
requested). The other two bytes are unused. They are present so 
thet the user's string will start on a longword boundry, for 
efficiency. 


When the user has no more use for a short string, the STR facilit 
does not deallocate it but instead puts it on a list of strings o 
its length, so that a later request can re-use the string space. 


A request to allocate a string longer than 240 bytes is satisfied by 
simply allocating it from free storage. Such a ane string’ has no 
header bytes, so it cannot be shortened, since its allocate lenges 
is kept onty in the DSCSW_LENGTH field. When the user is done with 
a “‘Long string’ the STR facility returns its data to the virtual | 
memory pool so it can be used again later, either for another string 
or ~~ sone other purpose, such as for holding infrmation about an 
opene e. 


The routines in the STR facility are AST-reentrant, so the user may 
allocate and deallocate strings both at non-AST level and at AST 


level. However, the process of copying data from one string to 
another may be interru ted, and when the interrupt resumes 


the PErine has moved, so it is the user's responsibility not to 
re-allocate a string at AST level which might be in use at non-AST 
Level. Within the STR facility strings are interlocked against 
destructive use at AST level, so the user will get error messages 
in many cases of this kind of string misuse, though not all. 


String interlocking is implemented using a queue of descriptors. 
Before reallocating a ye | (or, in general, doing any writing 
into a string) the STR$ routines check the queue to be sure that 
the string is not on it. Also, any string passed as a parameter 
to a STR$ routine is placed on the queue while the STR$ routine 
is using it. This allows the STR$ routines to be confident that 
the length and pointer fields of a string descriptor pavoes to 
them will not change because of an AST reallocating the string. 
In order for the user to pet this same level of protection, any 
string which could be reallocated at AST level me be accessed 
at non-AST level only by first making a copy of the lagen by 
ot a STRSCOPY_DX. If an AST tries to reallocate the string 
while it is being copied, an error will be signalled. 


i <BLF /PAGE> 
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he 
MOVC class of instructions do not re-examine the descriptor to see if 
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MACROS: 


14 
! The following are macros and Literals used by the STR$ 

'‘ RTL modules. The macro names are of the form 

: $STR$verb for macros that perform an action 

4 $STR$noun for macros that return a value 

SSTRS$condition for macros that check a condition and return T or F 


MACRO 
1+ 
: This macro is used to declare local storage for a descriptor 


SSTRSDESCRIPTOR = 
- BLOCK (8, BYTE) %, 


! This macro returns the length (current for VARYING) of a string of 
! any class or dtype. \This macro will have to add a case statement 
: f any string classes are added whose current length is not 
: in the same position as for fixed length strings\ 


le 
SSTRSLENGTH (DESCRIPTOR) = 
DESCRIPTOR CDSC$W_LENGTH] %, 


'¢ 
This macro returns the data type of a string. 


SSTRSDTYPE (DESCRIPTOR) = 
DESCRIPTOR CDSCSB_DTYPE) %, 


'¢ 
; This macro returns the class of a string 


SSTRSCLASS (DESCRIPTOR) = 
DESCRIPTOR CDSC$B_CLASS) 2%, 


'¢ 

! This macro returns the pointer to the string data. \This macro will have 
. to add a case statement if any string classes are suppertes whose 

‘ pointer in the descriptor does not point to the data 


SSTRSPOINTER (DESCRIPTOR) = 
DESCRIPTOR CDSCSA_POINTER] 2, 


This macro exchanges the length and pointer fields of 2 descriptors. 

It is designed to take the length and pointer from a local temp descriptor 
(descriptor_1) and exchange them with the length and pointer of a : 
destination parameter descriptor. Even though at the point of execution 
of this macro the interlock mechanism is in use to prevent anyone else 
from mney ten the destination descriptor, it would also provide AST 
reentrany for a reader of the destination string if a way could be found 
to move the Length and pointer in one instruction. 


SSTRSEXCH_DESCS (DESCRIPTOR_1, DESCRIPTOR_2) = 
BEGIN 


- 


LOCAL 
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SSTRSTEMP_DESC : SSTRSDESCRIPTOR; 
TRSLENGTH (SSTRSTEMP DESC) = .$STRSLENGTH Se 


$$ SCRIPTOR 2): 
SSTRSPOINTER (SSTRSTEMP_DESC) = .SSTRSPOINTER (DESCRIPTOR_2); 
%IF XBLISS (BLISS32) 
XZTHEN 

BEGIN 

EXTERNAL ROUTINE 

STRSSMOVQ_R1 : STRS$SJSB_MOVQ; 

SSTRSDTYPE (DESCRIPTOR_1) = .$STRSDTYPE (DESCRIPTOR_2); 

SSTRSCLASS (DESCRIPTOR@1) = SSTRSCLASS (DESCRIPTOR~2) 

STRSSMOVO_R1 (DESCRIPTOR_1 CO, 0, 0, 03, DESCRIPTOR~2 CO, 0, 0, 03): 
ZELSE 


BEGIN 
SSTRSLENGTH (DE 
SSTRSPOINTER (D 


“FI : 


SSTRSLENGTH (DESCRIPTOR 1) = .S$STRSLENGTH ($STR 
hati (DESCRIPTOR_1) = .S$STRSPOINTER ($S 


SCRIPT 
ESCRIP 


=O 


CRI 
SCR 


STEMP_DESC); 
TRSTEMP DESC); 


This macro is used to check for the occurrence of overlap of 2 operands. 
' If overlapping must be checked for more than 2 operands, this macro must 
be used to check all possible combinations of 2 qverssensme It is used 
! on VAX only if there is more than one source string and a destination 
string. It is used on other machines for any routine that has source and 
! destination strings. 


+ 


This aacre returns a TRUE if the 2 operands do overlap and a FALSE if they 
o not. 


cushy “1 ea (POINTER_1, LENGTH_1, POINTER_2, LENGTH_2) = 


IF POINTER_1 LSSA POINTER_2 
(POINTER_2 LSS (POINTER_1 + LENGTH_1)) 
(POINTER_1 LSS (POINTER_2 + LENGTH_2)) 


END 
x, 


o 
This macro checks to see if allocation is needed because enough space 
is not currently allocated to the destination. \It should be changed 
to cause allocation for overlapping operands on non_VAX systems. This 
means the input needs to be descriptors instead of Tengths.\ 


This macro returns a TRUE if allocation is needed and a FALSE if not. 
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A SSTRSNEED_ALLOC (SIZE_NEEDED, ALLOCATED_LEN) = 
BEGIN 
IF (ALLOCATED_LEN GEQU STRSK_MAXS/ZSTR) 
(SIZE_NEEDED NEQU ALLOCATED_LEN) 
(SIZE_NEEDED GTRU ALLOCATE®_LEN) 


END 
x, 
‘+ 


7 
| 
This macro returns the allocated length of a dynamic string. 
"  $STRSDYN _AL_LEN (DESCRIPTOR) = 
BEGIN 


A ciememitent (DESCRIPTOR) EQLU 0) 


ELSE 
IF (.$STRSLENGTH (DESCRIPTOR) GTRU STRSK_MAXSIZSTR) 
~SSTRSLENGTH (DESCRIPTOR) 
BEGIN 
LOC 


@enteeeeeneee eee eeeeeeeane 


Bete Se Se Se Se Se Se Se Se Se Se Se Se Se Se Be SH Se Se Be Se SH Se 


+ 


AL 
STRING_BLOCK : REF BLOCK C, BYTE) FIELD (STRSSHORT_FIELD); 


STRING BLOCK = ,$STRSPOINTER (DESCRIPTOR); 
gS TRING_GLOCK CSTR$W_ALLOC_LEN) 


‘+ 

! This macro allocates the requested amount of space to a string 

! and fills the Length field of the Soncripter with the requested Length 
MAL or STRS_INSVIRMEM 


SSTRSALLOCATE (LENGTH, DESCRIPTOR_ADDR) = 
BEGIN 


! the value of the macro is either STR$_NO 


RNAL 
STRSSV_INIT; ! Initialization flag 


LOCAL | 
RETURN_STATUS; ! value of the macro 

EXTERNAL ROUTINE m 
STRSSINIT : NOVALUE; ! Initializes the queues 

EXTE | 
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If the short string queues need initialization, initialize them. 


IF ( NOT .STRSSV_INIT) THEN STRSSINIT (); 


‘4 
Initialize the value of the macro 


RETURN_STATUS = STRS_NORMAL; 


‘4 
! If the requested length of the ey is short enough, get space 
! from the short queues. Otherwise call LIBSGET_VM for space. 


le 

ul (LENGTH LEQU STRSK_MAXSIZSTR) 

te. BEGIN 

The requested size is short, access the short queues. 


BUILTIN 
REMQUE; 


OCAL 
REMQUE_ADDR, 
TEMP; 
EXTERNAL ROUTINE 
STRSSALOC_SHORT; ! Get more space for short queues 
EXTERNAL 
STR$$Q_SHORT_O : STRSSSHORT_STR CSTRSK_NUM_SH_QS]; ! The short queues 


'¢ 
: If the requested size is zero, just produce a descriptor for the null string. 


IF (LENGTH EQLU 0) 
TEMP = 0 


L 

ALLOC _DONE ; 

REMQUE_ADDR = STR$$Q_SHORT_Q CLENGTH, 0); 
dO 

'¢ 


! There is no more space in the requested queue, and we haven't previously 
failed while trying to allocate space. Allocate more space for it. 


IF (WOT (REMQUE (..REMQUE_ADCR, TEMP))) 
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THEN 
ALLOC_DONE = 1 
LSE 


ALLOC_DONE = 0; 
RETURN_STATUS = STRSSALOC_SHORT (LENGTH); 
ees (.ALLOC_DONE OR (NOT .RETURN_STATUS)); 


4 

} cortnes” the descriptor a pointer to the data area of the allocated 
' string. 

leo 


IF .RETURN_STATUS 

THEN 
BEGIN 
SSTRSPOINTER (DESCRIPTOR_ADDR) = .TEMP; 
SSTRSLENGTH (DESCRIPTOR_ADDR) = LENGTH: 

END 

ELSE 
BEGIN 


'¢ 
! The requested iength is too long for the short queues. Allocate space 
: from virtual storage to hold the string. 


EXTERNAL ROUTINE 

LIBSGET_VM; ! Get virtual storage 
EXTERNAL LITERAL 

STRS_INSVIRMEM; ! Error code 


RETURN_STATUS = LIBSGET_VM (ZREF (LENGTH), SSTRSPOINTER (DESCRIPTOR_ADDR)); 


IF ( NOT .RETURN_STATUS) 
THEN RETURN_STATOS = STR$_INSVIRMEM 
ELSE SSTRSLENGTH (DESCRIPTOR_ADDR) = LENGTH; 


END; 


le 
Return the status 


.RETURN_STATUS 
END 


'¢ 

! This macro allocates temporary string space for fixed length string 

! computation. \Optimization should be done. Perhaps if the requested 

' Length is less than some N then the space could be allocated on the 
stack, otherwise in heap storage. Currently always gives heap storage\ 


SSTRSALLOC_TMP (LENGTH, DESCRIPTOR_ADDR) = 
SSTRSACLOCATE (LENGTH, DESCRIPTOR_ADDR) %, 
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t+ 
% This macro deallocates the space allocated to the string parameter 
SSTRSDEALLOCATE (DESCRIPTOR_ADDR) = 


L 
RETURN_STATUS; ' status of deallocate 


RETURN STATUS = STR$_NOR 
IF (.$STRSPOINTER (DESCRIPTOR ADDR) NEQU 0) 


m BEGIN 
i If the s suring is small, put on the appropriate short queue. Otherwise 
; call LIBSFREE_VM to return it to free storage. 
on Sete (DESCRIPTOR_ADDR) LEQ STRSK_MAXSIZSTR) 
BEGIN 


EXTERNAL 
STRS$Q_SHORT_Q : STRSSSHORT_STR CSTRSK_NUM_SH_QS); 


BUILTIN 
INSQUE ; 


CAL 
TNSQUE ADDR. 
ALLOC_CEN 
STRING BLOCK’ : REF BLOCK C, BYTE] FIELD (STRSSHORT_FIELD); 


STRING BLOCK = .$STRSPOINTER (DESCRIPTOR_ADDR); 
ALLOC_CENGTH = ; STRING apgeck x pSiney $W ALL Ot rit EN): 
INSQUE TADDR = STRS$OQ 0): 

INSQUE™ ¢ CO OSTRSPOINTER® Meathibton uot kS OM tate ADDR); 


END 
ELSE 
BEGIN 


EXTERNAL ROUTINE 
LIBSFREE_VM; 


EXTERNAL LITERAL 
STRS_FATINTERR; 


RETURN ptarys = LIBSFREE 
ZREF (.$STRSLENGTH (DESCRIPTOR ADDR)), 
SSTRSPOINTER (DESCRIPTOR -ADDR)T; 
IF ( NOT .RETURN_STATUS) THEN RETURN_STATUS = STRS_FATINTERR; 
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.RETURN_STATUS 
END 
%, 
14 


: This macro is the counterpart of SSTRSALLOC_TMP. It releases the temporary 
: lig space used in fixed length string computation. If the space is on 

' the stack (ie. the yengen in the descriptor is less than N) no action need 
: be taken. However if the temporary space is in heap storage, (length 
greater than N) the storage must be released. \currently always uses heap\ 


SSTRSDEALOC_TMP (DESCRIPTOR_ADDR) = 
SSTRSDEALLOCATE (DESCRIPTOR_ADDR) %, 


'¢ : 
: This macro is used to take a return status from STRSS$COPY_R_R8 or other 
! status filled by STR routines and signal the fatal errors and just 


! continue on success, qualified success or warning. It is to be used 
: only after all interlocks are removed. 


SSTRSSIGNAL_FATAL (STATUS) = 
IF (NOT .STATUS) THEN 
IF (.BLOCK CSTATUS, STSSV_SEVERITY] EQLU STSSK_SEVERE) 
THEN BEGIN 


EXTERNAL ROUTINE LIBSSTOP; 
A ae hel (. STATUS); 


'¢ 

! SSTRSCHECK_STATUS inspects the current status . a 

! If it finds it to be one of the fatal LIB$ status codes, it signals 
! the corresponding STR$ code. Some LIB$ statuses are converted to 
the corresponding STR$ statuses. Unknown status are left alone. 


SSTRSCHECK_STATUS (RETURN_STATUS) = 


BEGIN 
EXTERNAL ROUTINE 
STRSSCHECK_STATUS_R2 : STRSSCHECK_STATUS_LINKAGE ; 


RETURN STATUS = STRSSCHECK_STATUS_R2 ( .RETURN STATUS ) ; 
Ss 


+ 

This macro is the mechanism by which the string routines derive the 
length and address of the Ist data byte of any supported class of 
arn descriptor. It is isolated here as a macro to that it can 
be ified ( e.g. enhance to speed up the extraction of some classes 
of descriptors at the expense of others) by simply recompiling all 

of the string routines and not having to modifiy their sources. 


SSTRSGET_LEN_ADDR ( DESCRIPTOR_ADDR, LENGTH, DATA_ADDR ) = 


Poa? ae ca a ele, Re eae eae Re 
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BEGIN ' of macro 
gh ROUTINE 7m 
STRSANALYZE_SDESC_R1 : STRSANALYZE_SDESC_JSB_LINK NOVALUC ; 


'¢ 
i _Special-case the classes of descriptors in Version 2 


if, .DESCRIPTOR. ADDR CDOSC$B_CLASS] LEQU DSCSK_CLASS_D 


GIN 
LENGTH = .DESCRIPTOR_ADDR C DSC$W_LENGTH J 
: DATA_ADDR = .DESCRIPTOR_ADDR CDSCSA_ POINTERS : 


ELSE 


'¢ 


JSB to STRSANALYZE_SDESC_R1, computing LENGTH and DATA_ADDR. 
"BEGIN 
STRSANALYZE_SDESC_R1 ( .DESCRIPTOR_ADDR ; 
LENGTH, DATA_ ADDR): 
END 
: END ' of macro 
'<BLF /PAGE> 
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+ 


ALL interlocking macros are disabled pending further study. 
Problem with the commemted out code include 
1. if AST interrupts while interlocks are set and AST does 
unwind, there is no handler to remove interlocks, so 
interlock queue points into perpege- 
- If AST interrupts in BASIC RUN command 
while interlocks are set and AST does : : 
unwind of a BASIC frame which owns one of the interlocked strings, 
it will try to free the string, which will signal interlocked — 
which will be caught by BASIC RUN handler which will try to unwind, 
hence infinite Loop. . e 
! The following macros are used to support string interlocking. 
! SSTRSINTERLOCK does the declarations, ° 
SSTRSINTERLOCK_WRITE interlocks a string that is to be written, 
! SSTRSINTERLOCK_READ interlocks a string that is to be read, and | 
! SSTRSINTERLOCK_CLEAR releases the interlock on a string. 


SSTRSINTERLOCK takes one argument: the maximum number of strings 
! which can be interlocked. 


The other three macros take two arguments: the address of the 
: descriptor to be operated on and its number. Numbers can range 
from 0 to the maximum number of strings minus 1. 


ALL strings to be written should be interlocked first, followed by 
! all strings to be read. Strings must be cleared in the reverse of 
' the order in which they were interlocked. 


There is extra age pe ve —— for debugging Eavesrs which 
can be turned on and off by using the following DEBUG switch 


COMPILETIME STRSSK_DEBUG = 0; ! 1=>do extra checking 
! Q=>no checking 


| 
| 
ACRO 
SSTRSINTERLOCK (NUM_STRINGS) = : 
' LOCAL 
iZIF STRS$K_DEBUG %THEN 
i $STRSQUEUED_COUNT, 
‘ard 


SSTRSINTERLOCK_CONTROL_BLOCKS : VECTOR CNUM_STRINGS*4, LONG); | 


4 EXTERNAL ROUTINE 
: STRSSUNWDEQ; ! Dequeues strings on unwind 


' 
' 
' 
EXTERNAL 

STRSSQ_INTLK : VECTOR (2, LONG); 
; 


LITERAL 
SSTRSMAX_STRINGS = (NUM_STRINGS); 


iZ1F STRS$K_DEBUG XTHEN 
i SSTRSQUEUED_COUNT = 0; 


3 
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'ZFI 
i 


it ENABLE 
ii STRSSUNWDEQ (SSTRSQUEUED_COUNT); 


$58_NORMAL 


seein - +1 conn cach (DESCRIPTOR_ADDR, STRING_NUMBER) = 


BUILTIN | 
INSQUE; 


CAL | 

INSQUE ADDR, | 
INTERLOCK_ADDR : REF VECTOR (3, LONG); | 

‘RIF STRESK_ DEBUG | 
AFL CCSTRING SUNDER? LSS 0) OR ((STRING_NUMBER) GEQ SSTRSMAX_STRINGS)) | 

BEGIN | 


EXTERNAL LITERAL | 
STRS_FATINTERR; 


LIBSSTOP (STRS_FATINTERR); 
END; 


INTERLOCK_ADDR = (($STRSINTERLOCK Coeteet. BLOCKS C(STRING_NUMBER)*4] + 7) AND ( NOT 7)); 
INTERLOCK_ADDR (2) = DESCRIPTOR_ADDR 


IF (.STRS$Q_INTLK (OJ EQLA 0) 
THEN 


BEGIN 
STRS$Q_INTLK (1) 
STRS$Q_ INTLK (0) 


INSQUE_ADDR = STR$$Q_INTLK (1); 
it NOT (INSQUE (INTERLOCK_ADDR [0], ..INSQUE_ADDR))) 
BEGIN 


LOCAL | 
SRCH_STATUS; 


EXTERNAL ROUTINE 
STRSS$SRCH_INTLK; 


‘SIF STRS$K_DEBUG ZTHEN 
lest “$STRSQUEVED_COUNT = .$STRSQUEVED_COUNT + 1; 


STRS$$Q_INTLK (0); 


| 
} 
STRSS$Q_INTLK (0); 


ce 
STRMACROS.REQ; 1 16-SEP-1984 16:51:435.31 Page 15 


34 SRCH_STATUS = 
; STRSSSRCH_ INTLK (DESCRIPTOR_ADDR) 


is IF ( NOT .SRCH_STATUS) THEN LIBS$STOP (.SRCH_STATUS); 
i END 
BEGIN 
‘IF STRSS$K_DEBUG XTHEN 
ed “$STRSQUEUED_COUNT = .$STRSQUEUED_COUNT + 1; 
i STRS_NORMAL 
END 
END 
SS$_NORMAL 
SSTRSINTERLOCK READ (DESCRIPTOR_ADDR, STRING_NUMBER) = 


BUILTIN 
INSQUE ; 


CAL 
TNSQUE_A 
INTEREOCK. PRODR : REF VECTOR (3, LONG); 
ZF STRSSK DEBUG 
dF CCCSTRING JUMBER) LSS 0) OR ((STRING_NUMBER) GEQ SSTRSMAX_STRINGS)) 
BEGIN 


EXTERNAL LITERAL 
STRS_FATINTERR; 


LIBSSTOP (STRS_FATINTERR); 
END; 


INTERLOCK_ADDR 
(COSTES INT RLOCK CONTROL _BLOCKS C(STRING_NUMBER)*4] + 7) 


D ( NO 
INTERLOCK _ADDR (24 = DESCRIPTOR_ADDR; 
IF (.STRS$Q_INTLK [0] EQLA 0) 

THEN 


BEGIN 
STR$S$Q_INTLK (1) 
prases. INTLK (0) 


STR$$Q_INTLK (0); 
STRS$$Q_INTLK 03; 


pear: ADDR = STRS$OQ INTE (1); 
INSQUE™ (INTERLOCK_ADDR (0], . » INSQUF ADDR) ; 
iZ1F STRSS$K_DEBUG ZTHEN 


Se, 
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io SSTRSQUEVED_COUNT = .$STRSQUEUED_COUNT + 1; 

i END 

SS$_NORMAL 

SSTRSINTERLOCK. CLEAR (DESCRIPTOR_ADDR, STRING_NUMBER) = 


BUILTIN 
REMQUE; 


CAL 
REMQUE_ADDR 
INTERLOCK_ADDR : REF yeh A C3, LONG), 
TEMP : REF VECTOR (3, LONG) 
iZ1F STRSS$K_DEBUG 
XTHEN 
SxTERNAL LITERAL 
IF (CCSTRING_ NUMBER) LSS 0) OR ((STRING_NUMBER) GEQ $STRSMAX_STRINGS)) 


HEN 

LIBSSTOP (STRS_FATINTERR); 
IF (.STRS$$Q_INTLK (OJ EQLA 0) 
THEN 


BEGIN 
STRS$Q_INTLK C1] = STRS$SQ_INTLK (0); 
rae INTLK CO) = STRSSQ"INTLK (0); 


sey | ~ADOR = STR$$Q_INTLK C1); 
EMQUE”(..REMQUE_ADDR, TEMP); 
ZIF STRESK DEBUG ZTH 
SSTRSQUEVED. COUNT = .SSTRSQUEUVED_COUNT =- 1; 
IF (.$STRSQUEVED_COUNT LSS 0) THEN LIBSSTOP (STRS_FATINTERR); 


ure eee ADDR 
(CSSTRSINTERLOCK, CONTROL_BLOCKS C(STRING_NUMBER)*4)} + 7) 


iZIF saat | DEBUG ZTHEN 
F T.TEMP NEQA .INTERLOCK_ADDR) THEN LIBSSTOP (STRS_FATINTERR); 


Ft IF (. TEMP C2) NEQA DESCRIPTOR_ADDR) THEN LIBSSTOP (STRS_FATINTERR); 


ee ee ee EEE EE EE TEES EEE EE LG ae Oe a 


END 
$S$_NORMAL 


! <BLF /PAGE> 
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'¢ 
Define a default fill character to be used as pad in fixed length strings 


LITERAL 
STRSK_FILL_CHAR = X%C* '; 


‘4 

: Define Dynamic String Control Block (pointed to by descriptor). 

: ~etues ty the descriptor (DSCSA_POINTER) points to where the string is 
. Stored in the control block and the header is before that (negative offset). 


ELD 
STRSSHORT_FIELD = 
SET 


‘+ 
! Offset to word containing allocated length. Actually # of bytes following 
! which is also max. size of string that can be held in the control block. 
In other words this count does not include the space taken up by itself. 


STRSW_ALLOC_LEN = [-2, 0, 16, 0] 
TES; 


'¢ 
} Number cf bytes in the control block header. 


LITERAL 
STRSK_HED_LEN = 2; 


'¢ 

! no. of extra bytes that can be in string because next header doesn't 
! take up entire longword. (ie. residue is no. extra bytes 

: beyond n*STRSK_ALL_QUA in string area). 


LITERAL 
STRSK_RESIDUE = ZUPVAL - STRSK_HED_LEN; 


'¢ 

' Power of 2 of alocation unit (8) 

! MAINTENANCE NOTE: Some advantage is taken in the code that the 

! size of the Q header is the same as the quanta. Thus no shifting 

is needed in order to perform INSQUE and REMQUE, only adding offsets. 


LITERAL 

STRSK_ALL_POW = 3; 

te 

Number of bytes in allocation quanta 


LITERAL 
STRSK_ALL_QUA = 1°STRSK_ALL_POW; 


3 
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‘+ 
: Number of short queues, one queue for each allocation quanta. 
! With current peregeter settings, string area 

: sizes are 8, 16, 24 


LITERAL 

STRSK_NUM_SH_QS = 30; 

‘+ 

Max. size of string which can fit in short Qs. 


LITERAL 
STRSK_MAXSIZSTR = ((STRSK_NUM_SH_QS)*STRSK_ALL_QUA); 


+ 
Sizes of descriptors for all string types 


LITERAL 
STRSK_SIZE_FIX = 2 ! descriptor size for fixed eM strings 
STRSK_SIZE_VARY = g, i descriptor size for varying strings 
STRSK_SIZE_DYN = 2; ! descriptor size for dynamic strings 


‘+ 
: The following structure is used to access (and define) the queue 
: of short strings. It is vector of INSQUE/REMQUE quadwords. Each 
: quadword represents a queue of potential strings which can be 

: allocated to a requesting program. 


STRUCTURE 
STRSSSHORT_STR CI, SIDE; NJ = 
CN*ZUPVAL*2) 
(STRSSSHORT_STR + (SIDE + ((1 = 1) AND ( NOT (STRSK_ALL_QUA = 1))))); 


End of file STRMACROS.REQ 
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